Publishing NuGet Packages with Default Files Using Visual Studio

TLDR

• When developing NuGet packages that require default configuration files, it is recommended to use .NET Standard as the project target platform.
• Modern NuGet package development no longer requires an external .nuspec file; configurations can be set directly in the .csproj file.
• install.ps1 is only applicable to legacy projects using package.config and will not execute in PackageReference mode.
• If the target project uses PackageReference, files within the package will not be automatically copied to the project directory; this is a design limitation of NuGet.
• When supporting legacy .NET Framework projects, it is recommended to specify multi-targeting in the csproj using <TargetFrameworks>.

Project Configuration for NuGet Package Development

When developing a NuGet package, it is recommended to choose the .NET Standard platform to ensure cross-platform support. If you need to support legacy .NET Framework simultaneously, you can configure multi-targeting in the project file.

When you might encounter this: When you need to develop a package that supports both new and old projects and need to handle compatibility across different frameworks.

Example of configuring multi-targeting in .csproj:

<PropertyGroup>
  <TargetFrameworks>netstandard2.1;netstandard2.0;net45</TargetFrameworks>
</PropertyGroup>

Package information can be defined directly within the .csproj, eliminating the need for an additional .nuspec file:

<PropertyGroup>
  <AssemblyName>LibrarySample</AssemblyName>
  <Authors>Wing</Authors>
  <Version>0.0.1</Version>
  <Description>For testing</Description>
  <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

Publishing Packages with Default Files

To include default files (such as Config.json) in a package and handle them automatically during installation, you must configure them in the .csproj.

When you might encounter this: When your package needs to provide a default configuration file template and you want users to see the file in their project immediately after installation.

Project File Configuration

Use <ItemGroup> to include the file and set the packaging path:

<ItemGroup>
  <Content Include=".\Config.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <PackageCopyToOutput>true</PackageCopyToOutput>
  </Content>
  <None Include=".\install.ps1">
    <Pack>True</Pack>
    <PackagePath>tools</PackagePath>
  </None>
</ItemGroup>

Limitations of install.ps1

• install.ps1 is only executed in package.config mode.
• If the target project uses PackageReference (such as ASP.NET Core or modern .NET projects), install.ps1 will not execute, and files will not be automatically copied to the project directory.
• Even for .NET Framework projects, if PackageReference is used, install.ps1 will not be triggered, and files will not be copied automatically.

WARNING

NuGet.org only accepts license expressions approved by the Open Source Initiative or the Free Software Foundation. If using other licenses, please use PackageLicenseFile to specify the path to the license file.

Publishing and Verification

Once configured, right-click the project and select "Pack" to generate the .nupkg file.

When you might encounter this: When you need to publish your developed package to a NuGet Server (such as NuGet.org or a private server) for others to use.

Publishing Steps

1. Ensure the configuration is set to Release mode.
2. After packing, retrieve the .nupkg file from the bin/Release directory.
3. If using NuGet.org, you can upload it directly via the web interface; for private servers, use the nuget push command.

Verification Observations

• package.config mode: install.ps1 is executed during installation, files are correctly copied to the project directory, and set to "Content" and "Copy if newer".
• PackageReference mode: install.ps1 is not executed, and files are not automatically copied to the project directory. This is the current design behavior of NuGet; developers should inform users in the package documentation that they need to create the configuration file manually or handle default values at runtime via code.

Change Log

• 2022-11-08 Initial document creation.